home *** CD-ROM | disk | FTP | other *** search
/ MIDICraft's MIDINET CD-ROM / MIDICraft's MIDINET CD-ROM.iso / DOSUTILS / TXT2MIDI.DOC < prev    next >
Text File  |  1996-09-22  |  17KB  |  439 lines
  1.         ******************************
  2.             TXT2MIDI v1.5
  3.  
  4.         text mnemonics to midi binaries 
  5.               by Guenter Nagler 
  6.                 1995 
  7.           (gnagler@ihm.tu-graz.ac.at)
  8.         ******************************
  9.  
  10. [0] FEATURES
  11.     + compiles text into midi
  12.     + modify existing midi files with help of MIDI2TXT
  13.     + can be used to add text to midi files (copyright notice, lyric, ...)
  14.     + copy and loop patterns
  15.     + checks tact positions (marked as ".")
  16.     + named GM-program names
  17.     + additional text commands for Korg i2/i3 (e.g. bankdrum)
  18.     + C-like comments // and /* ... */
  19.     + mute and solo some channels 
  20.     + handles format 0 (all channels in a track) and format 1 midi files
  21.       (seperate tracks)
  22.     + tempo can be specified midi like (ticks/minute) or in beats/minute 
  23.     + sysex events (including GMReset, GSReset, GSExit)
  24.     + meta events (popular or unknown events)
  25.     + direct events (midi command bytes)
  26.     + compressing output by ommiting redunant midi command bytes
  27.  
  28. [1] BACKGROUND
  29. After writing the pendant MIDI2TXT program it was obvious to program
  30. a compiler to translate the text back to a midi binary. I used it to sequence 
  31. some music titles. When I bought my music workstation (including a more
  32. powerful sequencer) my use of MIDI2TXT/TXT2MIDI changed into an
  33. updating environment to make less compatible midi files full compatible.
  34. Another use possibility came up when I copied some excellent midi
  35. binaries from news://alt.binaries.sounds.midi . I converted one with
  36. MIDI2TXT into text, commented all commands that played notes in leading
  37. track and converted it back into another midi file (TXT2MIDI). The new 
  38. midi file played the full background of the music while I was able to 
  39. learn playing the lead voice for my own pleasure.
  40.  
  41. [2] FILES DESCRIPTION
  42.  
  43. TXT2MIDI.EXE.........compiler 
  44. TXT2MIDI.DOC.........this file, showing usage of TXT2MIDI.EXE
  45. MIDILEX.L............LEX source code for text to midi
  46. LEXYY.C..............output of flex compiling MIDILEX.L  
  47. TXT2MIDI.Y...........YACC source code for text to midi
  48. TXT2MIDI.H...........output of byacc compiling TXT2MIDI.Y
  49. TXT2MIDI.C...........output of byacc compiling TXT2MIDI.Y
  50. MIDIREAD.CPP.........reading and writing midi binaries.
  51. MIDIREAD.HPP.........prototypes for declarations in MIDIREAD.CPP
  52. TXT2MIDI.MAK.........make file for project
  53. TXT2MIDI.CFG.........compiler options for make
  54. TXT2MIDI.PRJ.........project for borland c++ compilers
  55. only TXT2MIDI.EXE is required to run program
  56.  
  57. [3] COPYRIGHT
  58.  
  59. TXT2MIDI (c) 1995 was created by Guenter Nagler.
  60.  
  61. TXT2MIDI is free and may be used as you wish with this one exception:
  62.  
  63.     You may NOT charge any fee or derive any profit for distribution
  64.     of TXT2MIDI.  Thus, you may NOT sell or bundle TXT2MIDI with any
  65.     product in a retail environment (shareware disk distribution, CD-ROM,
  66.     etc.) without permission of the author.
  67.  
  68. You may give TXT2MIDI to your friends, upload it to a BBS, or ftp it to
  69. another internet site, as long as you don't charge anything for it.
  70. Please send me a notice if you locate the program on a public BBS.
  71.  
  72. [4] DISCLAIMER
  73.  
  74. TXT2MIDI was designed to compile text file that are generated by
  75. MIDI2TXT. So I give no guarantees of the compiler results, especially 
  76. with text files that are not generated by MIDI2TXT.
  77. If you create an error free text file that can not be compiled
  78. correctly, please send a sample file to gnagler@ihm.tu-graz.ac.at . 
  79.  
  80. Use TXT2MIDI at your own risk.  Anything you do with TXT2MIDI is your
  81. responsibility, and not the author's.  Any damage caused to any person,
  82. computer, software, hardware, company, or business by running TXT2MIDI 
  83. is your responsibility, and the author will not be liable.
  84.  
  85. If you don't understand these terms, or are not sure of something, or
  86. are afraid something bad might come of using TXT2MIDI, don't  use  it!
  87. You are here forewarned.
  88.  
  89. [5] INSTALLATION
  90.  
  91. [MSDOS]
  92. Simply copy TXT2MIDI.EXE in a directory that is in your path.
  93.  
  94. [UNIX]
  95. compile sources with your C++ compiler (e.g. GNU Compiler g++):
  96.  
  97. g++ -o txt2midi txt2midi.c midiread.cpp lexyy.c
  98.  
  99. Hint:  Force your compiler to compile all files C++ (and not C)!
  100.     If your compiler won't compile *.c as C++ then rename them to 
  101.     *.cpp or *.C!
  102.  
  103. and run program
  104.  
  105. $ txt2midi
  106.  
  107.  
  108. [6] USAGE
  109.  
  110. usage: TXT2MIDI textfile.txt midifile.mid
  111.  
  112. TXT2MIDI has no options and translates the textfile.txt which contains
  113. a text representation of a midi file into binary.mid that should contain
  114. a valid midi file if the compiler does not complain about errors or warnings.
  115.  
  116. Warning:
  117.   Do not expect that MIDI2TXT + TXT2MIDI will produce a copy of the original
  118.   file! MIDI allows to encode its commands in different ways without 
  119.   changing the semantic of the notes (It is allowed to compress the 
  120.   midi file by ommiting redunant command bytes, but it is no duty).
  121.       
  122. [7] GRAMMAR
  123.  
  124. Extended BNF rules:
  125. -----------------------------------
  126. symbol ::= expr ;            rule for symbol
  127. expr can be:
  128. expr*                        optional list of expr's
  129. expr+                        repetition of expr's (at least 1)
  130. [expr]                       optional expr  (0 or 1 occurence)
  131. expr1 expr2 ... exprN        sequence of expr1 ... exprN (in this order)
  132. expr1|expr2|...|exprN        alternatives between expr1...exprN (choose one) 
  133. (expr)                       expr itself for grouping (e.g. ("+"|"-")*
  134. "mthd" "("                   keywords and operators (case sensitive, use 
  135.                  without " characters)
  136. // text                      comment until next line
  137. literal   ::=   characters enclosed in "..."  e.g. "Track 1"
  138.         (special characters can be escaped by preceding \
  139.         e.g. "\""  is " character itself
  140.  
  141. lexical symbols (in E-BNF):
  142. ---------------------------------------
  143.  
  144. digit     ::=   "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9" ;
  145. hexdigit  ::=   digit|"A"|"B"|"C"|"D"|"E"|"F"|"a"|"b"|"c"|"d"|"e"|"f" ;
  146. decnumber ::=   digit+ ;
  147. hexnumber ::=   "0" ("x"|"X") hexdigit+ 
  148.         | "$" hexdigit+
  149.         ;
  150. number    ::=   decnumber | hexnumber ;
  151. floatnumber ::= decnumber | decnumber "." decnumber ;
  152. notekey   ::=   "C"|"D"|"E"|"F"|"G"|"A"|"H"|"B"
  153.           | "c"|"d"|"e"|"f"|"g"|"a"|"h"|"b" ;
  154.             // notekey "h" used in German language is equal to
  155.             // notekey "b"
  156.  
  157. notename  ::=   notekey ["#" | "is" | "b" | "es"] decnumber ;
  158.             // only legal notes as known in music theory are allowed
  159.             // suffixes "is" and "es" are used in German language
  160.             // "is" is equal to "#"
  161.             // "es" is equal to "b"
  162.             // exceptions rules (in German language):
  163.             //     As is equal to Ab
  164.             //     Es is equal to Eb
  165.             //     Use F instead of Eis
  166.             //  Use C instead of His
  167.             //     Use As instead of Aes
  168.             //  Use Es instead of Ees
  169.             //  Use H instead of Ces
  170.             //  Use E instead of Fes
  171.  
  172. note      ::=   notename | number ;
  173.  
  174. programname ::= 
  175.   // korg i2/i3 only:
  176.   "Dr1"|"Dr2"|"Dr3"|"Dr4"|"Dr5"|"Dr6"|"Dr7"|"Dr8"| 
  177. // general midi programs:
  178.   "Piano"| "BritePiano"| "HammerPiano"| "HonkeyTonk"| "NewTines"| "DigiPiano"| "Harpsicord"| "Clav"|
  179.   "Celesta"| "Glocken"| "MusicBox"| "Vibes"| "Marimba"| "Xylophon"| "Tubular"| "Santur"|
  180.   "FullOrgan"| "PercOrgan"| "BX-3Organ"| "ChurchPipe"| "Positive"| "Musette"| "Harmonica"| "Tango"|
  181.   "ClassicGtr"| "A.Guitar"| "JazzGuitar"| "CleanGtr"| "MuteGuitar"| "OverDrive"| "DistGuitar"| "RockMonics"|
  182.   "JazzBass"| "DeepBass"| "PickBass"| "FretLess"| "SlapBass1"| "SlapBass2"| "SynthBass1"| "SynthBass2"|
  183.   "Violin"| "Viola"| "Cello"| "ContraBass"| "TremoloStr"| "Pizzicato"| "Harp"| "Timpani"|
  184.   "Marcato"| "SlowString"| "AnalogPad"| "StringPad"| "Choir"| "DooVoice"| "Voices"| "OrchHit"|
  185.   "Trumpet"| "Trombone"| "Tuba"| "MutedTrumpet"| "FrenchHorn"| "Brass"| "SynBrass1"| "SynBrass2"|
  186.   "SopranoSax"| "AltoSax"| "TenorSax"| "BariSax"| "SweetOboe"| "EnglishHorn"| "BasoonOboe"| "Clarinet"|
  187.   "Piccolo"| "Flute"| "Recorder"| "PanFlute"| "Bottle"| "Shakuhachi"|"Whistle"| "Ocarina"|
  188.   "SquareWave"| "SawWave"| "SynCalinope"| "SynChiff"| "Charang"| "AirChorus"| "Rezzo4ths"| "Bass&Lead"|
  189.   "Fantasia"| "WarmPad"| "PolyPad"| "GhostPad"| "BowedGlas"| "MetalPad"| "HaloPad"| "Sweep"|
  190.   "IceRain"| "SoundTrack"| "Crystal"| "Atmosphere"| "Brightness"| "Goblin"| "EchoDrop"| "StarTheme"|
  191.   "Sitar"| "Banjo"| "Shamisen"| "Koto"| "Kalimba"|"Scotland"|"Fiddle"| "Shanai"|
  192.   "MetalBell"| "Agogo"| "SteelDrums"| "Woodblock"| "Taiko"| "Tom"| "SynthTom"| "RevCymbal"|
  193.   "FretNoise"| "NoiseChiff"| "Seashore"| "Birds"| "Telephone"| "Helicopter"| "Stadium!!"| "GunShot"
  194.   ;
  195.  
  196. Grammar in extended BNF
  197. -----------------------------------
  198.  
  199. midifile ::= midisong
  200.   ;
  201.  
  202. midisong ::= songoption* midihead songoption* miditrack+
  203.   ;
  204.  
  205. songoption ::= "mute" channel+     // ignore these channels
  206.   | "solo" channel+                // use these channels only
  207.   ;
  208.  
  209. channel ::= number                 // only 1-16 are valid channels
  210.   ;                                // channel 10 should be used for drums
  211.  
  212. midihead ::= "mthd" [version] [unit] "end" "mthd"
  213.   ;
  214.  
  215. version ::= "version" number   // default version: 1
  216.   // currently only versions 0-2 are allowed
  217.   // version 0 = single multichannel track
  218.   // version 1 = some singlechannel tracks playing together
  219.   // version 2 = some multichannel tracks playing one after one
  220.  
  221. unit ::=  "unit" number              // default unit: 192
  222.   ;
  223.  
  224. miditrack ::= "mtrk" [ "(" channel ")" ] 
  225.          event* 
  226.           "end" "mtrk" 
  227.           ;
  228.  
  229. event ::= [ "[" channel "]" ] midievent
  230.   | "velocyon" number    // default is 127
  231.   | "velocyoff" number   // default is 0
  232.   | duration sep         // pause: delay between events
  233.   | "print" sep
  234.   | "transpose" ["+"|"-"] number sep 
  235.   | sep
  236.   | "copy" "part" literal ;         
  237.   | "part" literal 
  238.     event*
  239.     "end" "part" literal 
  240.     ;
  241.   | "loop" number 
  242.     event* 
  243.     "end" "loop"
  244.     ;
  245.  
  246. sep ::= ";" | "." ;           // "." checks of end of tact
  247.  
  248. midievent ::=
  249.     "seqnumber" number
  250.   | "text" literal
  251.   | "copyright" literal
  252.   | "trackname" literal
  253.   | "instrument" literal
  254.   | "lyric" literal
  255.   | "prefixchannel" channel  // following sysex or meta event is applied to this channel
  256.   | "prefixport"   number   // following sysex or meta event is applied to this port
  257.   | "smpteofs" number ":" number ":" number ":" number ":" number
  258.         // SMPTE offset hour:minute:second:frame:fractional_frame
  259.   | "tact" number "/" number number number  // tactnom / (2 ^^ tactdenom)  clicks/beat 32th/beat
  260.   | "tempo" number  // microseconds per quarternote
  261.   | "beats" floatnumber  // same as 60.000.000/tempo
  262.             // quarternotes per minute
  263.   | "key" literal      // literal must contain a valid key:
  264.     // "Cmin" "Cmaj" "1bmin" "1bmaj" ... "7bmaj" ... "7#min" "7#maj"
  265.   | "event"
  266.        bytes
  267.     "end" "event"
  268.   | "metaevent" number "(" number ")" // a) metaevent nr. 0-127 b) length
  269.        bytes             // length (number) must match number of bytes!
  270.     "end" "metaevent"    // metaevents are 0xff-codes
  271.   | "sysevent" "(" number ")"   // number of sysex data bytes
  272.        bytes            // length (number) must match number of bytes!
  273.     "end" "sysevent"    // sysevents are 0xf0-codes
  274.             // end sysevent code 0xf7 is appended automatically!
  275.   | "gmreset"        // common sysex command to set GM mode on
  276.   | "gsreset"        // common sysex command to set GS mode on (mainly used for Roland, Yamaha)
  277.   | "gsenter"        // same as command gsreset
  278.   | "gsexit"        // common sysex command to set GS mode off (mainly used for Roland, Yamaha)
  279.   | "program" (programname | number | ("A"|"B"|"C"|"D") number
  280.   | "control" number number
  281.   | "hbank" number
  282.   | "lbank" number
  283.   | "banka" 
  284.   | "bankb" 
  285.   | "bankc" 
  286.   | "bankd" 
  287.   | "bankdrum" // bank*:  korg i2/i3 only!
  288.   | "balance" ("left" | "right" | number)   
  289.       // number is a value between 0 and 127: 0 is left and 127 is right
  290.   | "hold" ("on" | "off" | number)
  291.   | "reverb" number
  292.   | "chorus" number
  293.   | "brightness" number
  294.   | "expression" number
  295.   | "pitchmodulation" number
  296.   | "wheel" number
  297.   | "breath" number
  298.   | "foot" number
  299.   | "portamentotime" number
  300.   | "portamento" number
  301.   | "data" number
  302.   | "volume" number
  303.   | "sustain" number
  304.   | "sostenuto" number
  305.   | "softpedal" number
  306.   | "datainc" number
  307.   | "datadec" number
  308.   | "highRPN" number
  309.   | "lowRPN" number
  310.   | "pitchbendrange" number
  311.   | "localon" 
  312.   | "localoff" 
  313.   | "silent" 
  314.   | "allnotesoff" 
  315.   | "omnioff" 
  316.   | "omnion"
  317.   | "monoon"
  318.   | "polyon"
  319.   | "songpos"  number number
  320.   | "songselect" number
  321.   | "tunerequest"
  322.   | "timingclock"
  323.   | "start"
  324.   | "continue"
  325.   | "stop"
  326.   | "activesensing"
  327.   | "polyaftertouch" note number 
  328.   | "aftertouch" number 
  329.   | "pitchbend" number  
  330.   | notename duration number sep  
  331.   | "+" notename (number|"velocyon") sep  
  332.   | "-" notename (number|"velocyoff) sep  
  333.   | "+" number   // note on 
  334.   | "-" number   // note off
  335.   ;
  336.  
  337. duration ::= 
  338.     number             // units as defined in header
  339.   | number "/" number  (tact units, e.g. 3/4)
  340.   ;
  341.  
  342. program ::= number | programname ;
  343.  
  344. bytes ::= (number|literal)+ ;
  345.  
  346. A midi file format documentation can be downloaded by anonymous ftp from
  347. location:
  348.   ftp://ftp.cs.ruu.nl/pub/MIDI/DOC  
  349.  
  350. Document "midifile" explains all terms used in this grammar.
  351.  
  352. [8] SAMPLE TEXT
  353.  
  354. // itsasin.mid                     // comment until end of line
  355. mthd                               // header
  356.   // 1 song
  357.   // 17 tracks
  358.   unit 120 // is 1/4               // 120 ticks = 1/4 tact
  359. end mthd                           // end header
  360.  
  361. mtrk
  362.   tact 4 / 4 24 8                  // typical 4/4 Tact 
  363.   metaevent 89(2) $00 $00 end metaevent
  364.   beats 128                        // 128 beats/min (quarter notes)
  365.   4/4. // tact 1
  366.   metaevent 6(26) "It's a sin. Pet Shop Boys." end metaevent
  367. end mtrk
  368.  
  369. mtrk($1)                           // track with channel (hex) 1
  370.   metaevent 33(1) $00 end metaevent
  371.   trackname "String Lead"
  372.   program AnalogPad
  373.   volume 119
  374.   4/4. // tact 1       // end of tact 1
  375.   4/4. // tact 2
  376.   4/4. // tact 3
  377.   4/4. // tact 4
  378.   +d#5 $40;            // note on with velocity $40 (hex 40 = 64 dec)
  379.   4/4. // tact 5
  380.   -d#5 $00;            // note off 
  381.   +d#6 $50;            // ; is  note separator  . is tact separator (optional)
  382.   +d#5 $50;
  383.   4/4. // tact 6       // duration in tact units
  384.   +c5 $50;
  385.   228;-c5 $00;         // duration in tick units
  386.   -d#5 $00;
  387.   -d#6 $00;
  388.   // rest of midi is cut
  389. end mtrk
  390.  
  391. [9] SUGGESTIONS / COMMENTS / BUG REPORTS / QUESTIONS
  392.  
  393.          WWW:    http://hgiicm.tu-graz.ac.at/Cpub
  394.           contains all my dos/unix midi programs
  395.          EMAIL:  gnagler@ihm.tu-graz.ac.at
  396.  
  397. [10] CHANGES
  398. v1.0 to v1.1: 
  399.   * beats floating-point-number is now allowed (e.g. beats 65.5)
  400.     (suggestion by: djeff@cobra.jpl.nasa.gov)
  401.  
  402.   * optional version field in header (default: is version 1)
  403.   * portability changes for Unix compatibility 
  404.      -  no stricmp/strnicmp calls
  405.      -  no dos.h if not compiling under __MSDOS__
  406. v1.1 to v1.2:
  407.   * keywords now must be followed by whitespace that they are recognized as
  408.     keywords (former: "Trumpets" was separated into words "Trumpet" and "s").
  409.   * invalid characters in the source text now produce "invalid character" 
  410.     error message instead of adding it to the output midi file (major bug, 
  411.     produced invalid midi file).
  412.   * uses less compression (only note on/off commands are compressed, 
  413.     i.e. collects a sequence of these commands to one command)
  414.     to produce safer compatible output for some sequencers.
  415.   * added new keywords:  GMReset, GSReset, GSEnter, GSExit
  416.  
  417. v1.2 to v1.3:
  418.   * added meta events mnemonics prefixchannel and prefixport
  419.   * added option -version
  420.   * fixed bug that failed to convert note names C-1 .. B-1 into 0..11
  421.   * added documentation for using German language note names
  422.  
  423. v1.3 to v1.4:
  424.   * fixed bug occuring in use of solo
  425.     where last used channel in a multi channel track is muted
  426.     (didn't close the track and caused invalid midi file)
  427.   * error added if using multiple channels in single channel tracks
  428.     (e.g. track reserved channel 10 and uses other too)
  429.   * fixed bug when using solo,mute in multi channel track: 
  430.     illegal write of delta time for command on mute channel
  431.   * added control commands highRPN and lowRPN and pitchbendrange
  432.   
  433. v1.4 to v1.5:
  434.   * Warning if channel of a track is not initialized
  435.   * fixed bug that disabled "program number" command
  436.     for certain numbers (e.g. 0)
  437.   * forbidding channel numbers out of range 1-16
  438.   * bug fixed in literals converting characters written hex (e.g. \x82 )
  439.   * added command XGreset